home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / ical.z / ical / man / cat1 / ical.1
Text File  |  1994-09-27  |  23KB  |  595 lines
  1.  
  2.  
  3.  
  4. ICAL(1)                  USER COMMANDS           October 27, 1993
  5.  
  6.  
  7.  
  8. NAME
  9.      ical - X based calendar program
  10.  
  11. DESCRIPTION
  12.      _I_c_a_l provides an X interface for maintaining a calendar.   A
  13.      calendar is basically just a set of items. An item is either
  14.      an appointment, or a notice. An appointment starts at a par-
  15.      ticular  time  of the day, and finishes at a particular time
  16.      of the day. A notice does not have any  starting  or  ending
  17.      time.  Notices  are  useful for marking certain days as spe-
  18.      cial. For example, a calendar may contain a notice for April
  19.      15th  indicating that taxes are due.  When the documentation
  20.      below refers to an _i_t_e_m, it  applies  both  to  notices  and
  21.      appointments.  The main features of _i_c_a_l are:
  22.          * Items can be created edited and deleted easily.
  23.          * Items can be cut, copied and pasted.
  24.          * Items can be made to repeat in various ways.
  25.          * _I_c_a_l will post reminders for upcoming appointments.
  26.          * _I_c_a_l can print and list item occurrences.
  27.          * An _i_c_a_l calendar can include other calendars.
  28.          * _I_c_a_l calendars can be shared by different users.
  29.  
  30. GENERAL OPTIONS
  31.      You can specify various  command  line  options  to  control
  32.      _i_c_a_l.   The  following general options can be used even when
  33.      you are not logged in on an X display.
  34.  
  35.      -calendar _f_i_l_e-_n_a_m_e
  36.           The calendar is read from the specified file.  See  the
  37.           section ``CALENDAR FILE'' for more information.
  38.  
  39.      -list
  40.           Print a listing of today's items and exit  immediately.
  41.           See  the  section  ``LISTING ITEMS'' for details on the
  42.           actual items printed by this option.
  43.  
  44.      -show +_d_a_y_s
  45.           Print   a   listing   for   items    in    the    range
  46.           [ today ... today + _d_a_y_s  - 1 ]  and  exit immediately.
  47.           See the section ``LISTING ITEMS'' for  details  on  the
  48.           actual items printed by this option.
  49.  
  50. X OPTIONS
  51.      The following options are valid only if you are logged in on
  52.      an X display.
  53.  
  54.      -iconic
  55.           Start up with the main window iconified.
  56.  
  57.      -popup
  58.           Popup a window containing a listing  of  today's  items
  59.           and  exit  as soon as the window is dismissed.  See the
  60.  
  61.  
  62.  
  63. ReadyPak                                                        1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ICAL(1)                  USER COMMANDS           October 27, 1993
  71.  
  72.  
  73.  
  74.           section ``LISTING ITEMS'' for  details  on  the  actual
  75.           items printed by this option.
  76.  
  77.      -mono
  78.           Do not use colors even if the display supports them.
  79.  
  80.      -geometry _g_e_o_m_e_t_r_y
  81.           Use _g_e_o_m_e_t_r_y as the geometry for the main window.
  82.  
  83.      -fg _c_o_l_o_r
  84.           Use _c_o_l_o_r as the foreground for all windows.
  85.  
  86.      -bg _c_o_l_o_r
  87.           Use _c_o_l_o_r as the background for all windows.
  88.  
  89.      -display  _d_i_s_p_l_a_y
  90.           Run _i_c_a_l on the specified X display.
  91.  
  92. CALENDAR FILE
  93.      A calendar is stored in a calendar file. The default  calen-
  94.      dar  file  is  named ``.calendar'' and is kept in the user's
  95.      home directory. If the ``CALENDAR'' environment variable  is
  96.      set, its value is used as the name of the calendar file. The
  97.      ``CALENDAR'' environment variable and the default  can  both
  98.      be  overridden by specifying a file name on the command line
  99.      - ``ical -calendar _f_i_l_e-_n_a_m_e''.  _I_c_a_l periodically saves any
  100.      modifications made to a calendar to the corresponding calen-
  101.      dar file. Changes can be explicitly saved  to  the  calendar
  102.      file  by  selecting  the _S_a_v_e entry from the _F_i_l_e menu.  You
  103.      can discard any un-saved changes made  to  the  calendar  by
  104.      selecting  the _R_e-_R_e_a_d entry from the _F_i_l_e menu. The _R_e-_R_e_a_d
  105.      entry is also useful for incorporating  changes  made  to  a
  106.      shared  calendar by other users.  The _E_x_i_t entry in the _F_i_l_e
  107.      menu saves any changes and then kills the calendar program.
  108.  
  109. WINDOWS
  110.      The main  calendar  window  displays  the  appointments  and
  111.      notices  for a particular date.  The top left portion of the
  112.      window contains a date selector. You can click on the  vari-
  113.      ous  arrows to change the month or the year.  The day of the
  114.      month can be selected by clicking on the appropriate day  in
  115.      the month display.  The date selector contains various other
  116.      buttons for convenient date selection.  The bottom left por-
  117.      tion  of  the  window  contains the notices for the selected
  118.      date. You can scroll this region by using  the  scroll  bar.
  119.      The  right  portion  of the window contains the appointments
  120.      for the selected day. You can scroll this  region  by  using
  121.      the  scroll bar, or by dragging with the middle mouse button
  122.      in the background.  A menubar runs  along  the  top  of  the
  123.      calendar  window.   The  _F_i_l_e  menu allows you to create and
  124.      destroy application windows.
  125.  
  126.  
  127.  
  128.  
  129. ReadyPak                                                        2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ICAL(1)                  USER COMMANDS           October 27, 1993
  137.  
  138.  
  139.  
  140.      New Window
  141.           Opens a new calendar window. This  new  window  can  be
  142.           used  to  view  the items for a different date than the
  143.           original window.
  144.  
  145.      Close Window
  146.           Closes the selected window.
  147.  
  148.      The bottom portion of the window  contains  a  status  line.
  149.      This  status  line  indicates  the  calendar  from which the
  150.      selected item comes and whether or  not  the  selected  item
  151.      repeats.
  152.  
  153. NOTICES
  154.      You can enter notices by clicking in the background  in  the
  155.      bottom-left  portion of the main calendar window. This click
  156.      will create a new notice for the  selected  date.   You  can
  157.      enter  text  into  the  notice by typing into it while it is
  158.      selected  (selected  notices  are   highlighted   by   being
  159.      displayed  in  different  colors).  A notice can be selected
  160.      for editing by clicking with left button.
  161.  
  162. APPOINTMENTS
  163.      You can enter appointments by  left-clicking  in  the  back-
  164.      ground  in  the  right  portion of the main calendar window.
  165.      This click will create a new appointment  for  the  selected
  166.      date.  The  start time for this appointment is determined by
  167.      the click location. You can move the appointment by dragging
  168.      it  with  the middle mouse button held down. The appointment
  169.      can be resized by dragging with the right mouse button  held
  170.      down.   Appointment  text  can  be edited by typing into the
  171.      appointment window while it is selected.  If the appointment
  172.      text  you  are  typing  in does not fit into the appointment
  173.      area, then it will overflow out of the appointment area, but
  174.      will  be  editable normally.  If you do not like overflowing
  175.      text, you should turn off the _A_l_l_o_w _T_e_x_t _O_v_e_r_f_l_o_w option  in
  176.      the  _O_p_t_i_o_n_s  menu.   With  this  option  turned off, if the
  177.      current text completely fills  the  area  allocated  to  the
  178.      appointment,  then  any  attempts  to add to the appointment
  179.      text will be ignored until the appointment is enlarged  with
  180.      the  right  mouse  button.  Likewise, the right mouse button
  181.      will refuse to shrink an appointment window if the  appoint-
  182.      ment text completely fills the appointment window.
  183.  
  184. ALARMS
  185.      _I_c_a_l generates alarms  for  appointments.  By  default,  the
  186.      first alarm is generated fifteen minutes before the appoint-
  187.      ment is supposed to start and  successive  alarms  are  gen-
  188.      erated  every  five  minutes  until the appointment actually
  189.      starts.  You can change this default behavior  by  selecting
  190.      the _D_e_f_a_u_l_t _A_l_a_r_m_s entry from the _O_p_t_i_o_n menu.  You can also
  191.      change the timings of these  alarms  on  an  appointment-by-
  192.  
  193.  
  194.  
  195. ReadyPak                                                        3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ICAL(1)                  USER COMMANDS           October 27, 1993
  203.  
  204.  
  205.  
  206.      appointment  basis  by  selecting  an  appointment  and then
  207.      selecting the _C_h_a_n_g_e _A_l_a_r_m_s entry in the _E_d_i_t menu.
  208.  
  209. REPEATING ITEMS
  210.      Items can be made to repeat in various ways. Item repetition
  211.      can  be  controlled by using the entries in the _R_e_p_e_a_t menu.
  212.      These entries make the item  repeat  in  certain  frequently
  213.      used ways. For example, the _M_o_n_t_h_l_y entry makes the selected
  214.      item repeat once per month.  In addition to making  an  item
  215.      repeat in one of the pre-defined ways, you can also restrict
  216.      an item's starting and finishing date by selecting the  _M_a_k_e
  217.      _F_i_r_s_t _D_a_t_e or the _M_a_k_e _L_a_s_t _D_a_t_e entry from the _R_e_p_e_a_t menu.
  218.      Normally, a modication to a repeating item  applies  to  all
  219.      occurrences of that item. A single occurrence of a repeating
  220.      item can be modified by selecting the  occurrence  and  then
  221.      choosing  the  _M_a_k_e  _U_n_i_q_u_e  entry  from the _E_d_i_t menu.  The
  222.      selected occurrence can now be modified independently of the
  223.      repeating item.
  224.  
  225. X SELECTION
  226.      Dragging with the left mouse button in a  selected  appoint-
  227.      ment or notice sets the X selection.  You can use the _I_n_s_e_r_t
  228.      _S_e_l_e_c_t_i_o_n entry in the _E_d_i_t menu to  insert  the  current  X
  229.      selection  into  a  selected  item.   You can use the _I_m_p_o_r_t
  230.      _S_e_l_e_c_t_i_o_n entry in the edit menu to  insert  the  current  X
  231.      selection as a new item.  _I_c_a_l guesses the date and time for
  232.      the new item from the contents of the selection.
  233.  
  234. CLIPBOARD
  235.      The application has a clipboard  that  can  store  a  single
  236.      item.  The  _C_o_p_y  entry in the _E_d_i_t menu copies the selected
  237.      item into the clipboard.  The _C_u_t entry does the  same,  but
  238.      it  also deletes the item from the calendar. If the selected
  239.      item repeats, then the _C_u_t command allows the user to delete
  240.      all   occurrences   of   the  item,  or  just  the  selected
  241.      occurrence.  However, if the selected item does  not  belong
  242.      to you, then _C_u_t just hides the item from you.  Other people
  243.      will still see the item.  An item in the  clipboard  can  be
  244.      inserted  into  the  current day by selecting _P_a_s_t_e from the
  245.      _E_d_i_t menu. The newly pasted item loses all repetition infor-
  246.      mation, and occurs just on the day in which it was pasted.
  247.  
  248. HIGHLIGHTING ITEMS
  249.      By default, if any item occurs on a date, then the  date  is
  250.      highlighted  in  the  date  selector located in the top-left
  251.      corner of the calendar window.  You can use  the  _H_i_g_h_h_l_i_g_h_t
  252.      sub-menu  in  the  _E_d_i_t  menu  to  control this highlighting
  253.      behavior on an item-by-item basis.
  254.  
  255.      Always
  256.           The item always causes the  corresponding  date  to  be
  257.           highlighted.  This is the default behavior.
  258.  
  259.  
  260.  
  261. ReadyPak                                                        4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. ICAL(1)                  USER COMMANDS           October 27, 1993
  269.  
  270.  
  271.  
  272.      Until Occurrence
  273.           The  item  causes  the   corresponding   date   to   be
  274.           highlighted if and only if the date is not in the past.
  275.  
  276.      Never
  277.           The item never causes  the  corresponding  date  to  be
  278.           highlighted.
  279.  
  280.      As Holiday
  281.           The  item  causes  the   corresponding   date   to   be
  282.           highlighted as a holiday.
  283.  
  284. LISTING ITEMS
  285.      You can generate listings of imminent items by selecting one
  286.      of  the  listing options in the _L_i_s_t menu.  You can also use
  287.      the command line options -list, -show, or -popup to generate
  288.      item  listings.  The command line options are most useful in
  289.      ``.login'' files.  By default an item is included in a list-
  290.      ing  for a particular date if it occurs either on that date,
  291.      or on the very next day. Sometimes, you want to  include  an
  292.      item in listings for earlier dates. For example, if you have
  293.      an item reminding you of a birthday on March 17th, you might
  294.      want this item to be included in all listings from March 7th
  295.      to March 17th so that you will have enough time  to  go  out
  296.      and buy a present.  You can achieve this effect by selecting
  297.      the _T_e_n _D_a_y_s _E_a_r_l_y option from the _L_i_s_t _I_t_e_m  entry  in  the
  298.      _E_d_i_t  menu.   Note  that  this  will only change the listing
  299.      behavior for the selected item.  You can  make  this  change
  300.      for  all  items  you create from now on by using the _D_e_f_a_u_l_t
  301.      _L_i_s_t_i_n_g_s entry in the _O_p_t_i_o_n_s menu.  The _A _D_a_y  _E_a_r_l_y  entry
  302.      restores  the default behavior. The _O_n _O_c_c_u_r_e_n_c_e entry marks
  303.      the item so that it is only included in the  listing  for  a
  304.      particular date if it occurs on that date.
  305.  
  306. PRINTING
  307.      Calendar contents can be  printed  by  selecting  the  _P_r_i_n_t
  308.      option  from the _F_i_l_e menu.  The user has the option of sav-
  309.      ing the print-out to a file,  previewing  the  print-out  by
  310.      specifying  a  PostScript displaying program, or sending the
  311.      print-out directly to a PostScript printer.
  312.  
  313. INCLUDING CALENDARS
  314.      You can include other calendars into your private  calendar.
  315.      This  facility is mainly useful for allowing a group of peo-
  316.      ple to share a common set of items. For example, members  of
  317.      a  particular  group might have a calendar that contains the
  318.      birthdays for each member of the group. This calendar can be
  319.      included  in  each group member's private calendar.  You can
  320.      include a calendar by selecting the _I_n_c_l_u_d_e  _C_a_l_e_n_d_a_r  entry
  321.      from  the  _F_i_l_e menu. You can remove an included calendar by
  322.      selecting the _R_e_m_o_v_e _C_a_l_e_n_d_a_r entry from the _F_i_l_e menu.   An
  323.      item  can  be  moved between calendars by selecting the _M_o_v_e
  324.  
  325.  
  326.  
  327. ReadyPak                                                        5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. ICAL(1)                  USER COMMANDS           October 27, 1993
  335.  
  336.  
  337.  
  338.      _I_t_e_m _T_o ... entry from the _E_d_i_t  menu.   You  can  list  all
  339.      items  in a particular calendar by selecting the _F_r_o_m _C_a_l_e_n_-
  340.      _d_a_r ... entry from the _L_i_s_t menu.
  341.  
  342. CUSTOMIZATION
  343.      Limited portions of _i_c_a_l can be customized via  the  _O_p_t_i_o_n_s
  344.      menu.
  345.  
  346.      Appointment Range
  347.           Subset of a day displayed by default in the appointment
  348.           listing.    The  factory  settings  display  8:00am  to
  349.           6:00pm.
  350.  
  351.      Notice Window Height
  352.           This entry can be used to  change  the  height  of  the
  353.           notice window.
  354.  
  355.      Item Width
  356.           This entry can be used to change the width of displayed
  357.           appointments and notices.
  358.  
  359.      Allow Text Overflow
  360.           If this option is selected, then you can  type  in  any
  361.           amount  of  text  into an appointment.  The part of the
  362.           text that does not fit into  the  appointment  will  be
  363.           allowed  to overflow out of the appointment.  If you do
  364.           not like text overflowing out of an  appointment,  then
  365.           you should turn off this option.
  366.  
  367.      Display Am/Pm
  368.           If this option is selected, time  will  be  printed  in
  369.           twelve  hour  mode  with  ``am''  or ``pm'' indicators.
  370.           Otherwise, time will be  printed  in  twenty-four  hour
  371.           mode.
  372.  
  373.      Start Week on Monday
  374.           If this option is selected, month displays  will  start
  375.           each  week  off on a Monday.  Otherwise, each week will
  376.           start on a Sunday.
  377.  
  378.      Default Alarms
  379.           Use this menu entry to change  the  time  intervals  at
  380.           which alarms go off.  The factory settings cause alarms
  381.           to be triggered fifteen minutes  before  each  appoint-
  382.           ment,  and  then  once  every  five  minutes  until the
  383.           appointment actually starts.  This menu  entry  changes
  384.           the  default  alarm behavior for all appointments.  You
  385.           can override this default behavior on  an  appointment-
  386.           by-appointment  basis  by  selecting an appointment and
  387.           then selecting the _C_h_a_n_g_e  _A_l_a_r_m_s  entry  in  the  _E_d_i_t
  388.           menu.
  389.  
  390.  
  391.  
  392.  
  393. ReadyPak                                                        6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. ICAL(1)                  USER COMMANDS           October 27, 1993
  401.  
  402.  
  403.  
  404.      Default Listings
  405.           This menu can be used to  select  the  default  listing
  406.           behavior for newly created items.  If the _O_n _O_c_c_u_r_r_e_n_c_e
  407.           entry is selected, then a newly created item will  only
  408.           be  shown  in  the listing of the day on which the item
  409.           occurs.  If the _A _D_a_y _E_a_r_l_y entry is selected,  then  a
  410.           new  item  will  be  shown  in  listings starting a day
  411.           before the item occurrence.  Similarly, the other  menu
  412.           entries  can  be  selected to make new items show up in
  413.           listings  a  number  of  days   before   their   actual
  414.           occurrence.  This menu selects the default behavior for
  415.           new items.  Individual item behavior can be  controlled
  416.           by similar entries in the _E_d_i_t menu.
  417.  
  418.      You can specify several X resources to customize the rest of
  419.      the appearance and behavior of _i_c_a_l.
  420.  
  421.   BEHAVIOR
  422.      Ical.pollSeconds
  423.           Calendar files are saved, and  changes  made  by  other
  424.           people are incorporated once every _p_o_l_l_S_e_c_o_n_d_s seconds.
  425.           The default value is 30.  If _i_c_a_l appears sluggish,  or
  426.           if it is using too much CPU time, increase this value.
  427.  
  428.   DIMENSIONS
  429.      Ical.itemSelectWidth
  430.           The border width of selected items is set to the  value
  431.           of  this  option  to display the selected status of the
  432.           item to to the user.  On color  displays,  the  default
  433.           value of this option is ``1'' because on color displays
  434.           selection is indicated by changing  the  color  of  the
  435.           selected  item.   On  monochrome  displays, the default
  436.           value of _i_t_e_m_S_e_l_e_c_t_W_i_d_t_h is ``4''.
  437.  
  438.      Ical.Dayview.geometry
  439.           X geometry  specification  for  main  calendar  window.
  440.           Usually,  you  will  just  specify  the window position
  441.           here.  The size of the window is easier to control  via
  442.           the _O_p_t_i_o_n_s menu.
  443.  
  444.      Ical.Reminder.geometry
  445.           X geometry specification for alarms.  Usually, you will
  446.           just specify the window position here.  The window size
  447.           will be calculated automatically.
  448.  
  449.      Ical.Listing.geometry
  450.           X geometry specification for item  listings.   Usually,
  451.           you  will  just  specify the window position here.  The
  452.           window size will be calculated automatically.
  453.  
  454.   COLORS
  455.      If _i_c_a_l windows show up with illegible  colors  (not  enough
  456.  
  457.  
  458.  
  459. ReadyPak                                                        7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. ICAL(1)                  USER COMMANDS           October 27, 1993
  467.  
  468.  
  469.  
  470.      distinction  between  background  and foreground), it may be
  471.      because your X resources contain  definitions  for  ``*fore-
  472.      ground''  or ``*background'' that conflict with _i_c_a_l colors.
  473.      In general, it is a bad idea to define  ``*foreground''  and
  474.      ``*background''  in  your  resources because it will break a
  475.      number  of  programs.   You  will  be  better  off  defining
  476.      resources on an application by application basis.
  477.  
  478.      Ical*foreground
  479.      Ical*background
  480.           Set the colors used for most of the _i_c_a_l windows.
  481.  
  482.      Ical.itemFg
  483.      Ical.itemBg
  484.           The foreground and  background  colors  for  unselected
  485.           items.  The default foreground is black and the default
  486.           background is gray.
  487.  
  488.      Ical.itemSelectFg
  489.      Ical.itemSelectBg
  490.           The  foreground  and  background  colors  for  selected
  491.           items.   The  default  foreground  is  yellow  and  the
  492.           default background is blue.
  493.  
  494.      Ical.apptLineColor
  495.           The color for the background lines and times  displayed
  496.           in the appointment window.
  497.  
  498.      Ical.weekdayColor
  499.           The color used  to  display  days  of  the  week.   The
  500.           default is black.
  501.  
  502.      Ical.weekendColor
  503.           The color used to display  weekends.   The  default  is
  504.           red.
  505.  
  506.      Ical.interestColor
  507.           The color used to  highlight  interesting  dates.   The
  508.           default is blue.
  509.  
  510.   FONTS
  511.      Ical.fontFamily
  512.           Preferred font family.  Fonts for various purposes  are
  513.           obtained from this family unless overridden with one of
  514.           the specifications below.  The default font  family  is
  515.           ``times''.   Some  other  font families you can specify
  516.           here are ``charter'', ``new century  schoolbook'',  and
  517.           ``helvetica''.
  518.  
  519.      Ical.itemFont
  520.           Font used to display item contents.
  521.  
  522.  
  523.  
  524.  
  525. ReadyPak                                                        8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. ICAL(1)                  USER COMMANDS           October 27, 1993
  533.  
  534.  
  535.  
  536.      Ical.weekdayFont
  537.           Font used for displaying days of the week.
  538.  
  539.      Ical.weekendFont
  540.           Font used for displaying weekends.
  541.  
  542.      Ical.interestFont
  543.           Font used to highlight interesting dates.
  544.  
  545.      Ical.smallHeadingFont
  546.           Font used for small headings.
  547.  
  548.      Ical.largeHeadingFont
  549.           Font used for large headings.
  550.  
  551.      Ical*<_c_l_a_s_s>*font:
  552.           Font used for windows of  a  certain  class.   Possible
  553.           values   for   <_c_l_a_s_s>   are   ``Dialog'',  ``Button'',
  554.           ``Label'', ``Menubutton'', ``Menu'',  ``Listbox'',  and
  555.           ``Reminder''.
  556.  
  557. AUTHOR
  558.      Sanjay Ghemawat (sanjay@lcs.mit.edu)
  559.  
  560. COPYRIGHT
  561.      Copyright  (c)  1993  by  Sanjay  Ghemawat.   Permission  is
  562.      granted  to  make  and  distribute  verbatim  copies of this
  563.      manual provided the copyright  notice  and  this  permission
  564.      notice are preserved on all copies.
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591. ReadyPak                                                        9
  592.  
  593.  
  594.  
  595.